import {
  Intro,
  Meta,
  MediaQueriesTable,
  CustomPropertiesTable,
  Color,
  Spacing,
  IconSize,
  BorderRadius,
  BorderWidth,
  FontStack,
  FontWeight,
  LetterSpacing,
  Typography,
  Transition,
} from '../../.storybook/components';

<Meta title="Features/Theme" />

# Theme

<Intro>

The theme used throughout Circuit UI comes from SumUp's design token library, [`@sumup-oss/design-tokens`](Packages/design-tokens/Docs), which is a required peer dependency of `@sumup-oss/circuit-ui`. Refer to its [documentation](Packages/design-tokens/Docs) for installation and usage instructions.

</Intro>

Circuit UI's [ESLint plugin](Packages/eslint-plugin-circuit-ui/Docs)  includes rules (`no-invalid-custom-properties` and `prefer-custom-properties`) to ensure proper usage of the design tokens.

## Colors

### Background colors

<CustomPropertiesTable namespace="bg" type="color" preview={Color} />

### Foreground colors

<CustomPropertiesTable namespace="fg" type="color" preview={Color} />

### Border colors

<CustomPropertiesTable namespace="border" type="color" preview={Color} />

## Spacings

Use spacings for gutters, margins, and paddings. Don't use it for border width, border radius, icon size, font size, or line height. Use the dedicated design tokens instead.

<CustomPropertiesTable namespace="spacings" preview={Spacing} />

## Icon sizes

<CustomPropertiesTable namespace="icon-sizes" preview={IconSize} />

## Border radius

<CustomPropertiesTable namespace="border-radius" preview={BorderRadius} />

## Border width

<CustomPropertiesTable namespace="border-width" preview={BorderWidth} />

## Typography

Avoid using the typography CSS custom properties directly in your styles. Instead, use the typography components [`Display`](Typography/Display/Docs), [`Headline`](Typography/Headline/Docs), [`Body`](Typography/Body/Docs) and [`Numeral`](Typography/Numeral/Docs).

<CustomPropertiesTable
  namespace={[
    'body',
    'display',
    'headline',
    'compact',
    'numeral',
    'typography',
  ]}
  preview={Typography}
/>

## Font stack

<CustomPropertiesTable namespace="font-stack" preview={FontStack} />

## Font weight

<CustomPropertiesTable namespace="font-weight" preview={FontWeight} />

Pass the `weight` prop to the `Body` component to adjust its font-weight styling. The font weight of the `Display`, `Headline` and the `Numeral` components is bold by default and should not be overwritten.

## Letter spacing

<CustomPropertiesTable namespace="letter-spacing" preview={LetterSpacing} />

## Transitions

<CustomPropertiesTable namespace="transitions" preview={Transition} />

## Z-index

Z-indices for various components to ensure they stack properly.

<CustomPropertiesTable namespace="z-index" />

## Legacy

The following properties haven't been translated to CSS custom properties and are only available as part of the JS theme. They will be removed eventually.

### Grid

```
theme.grid.<BREAKPOINT>.[priority|breakpoint|cols|maxWidth|gutter]
```

Refer to the [`Grid`](Layout/Grid/Docs) documentation for an overview of the grid system.

### Breakpoints and media queries

```
theme.mq.[untilKilo|kilo|kiloToMega|mega|untilMega|megaToGiga|giga|gigaToTera|tera]
theme.breakpoints.[untilKilo|kilo|kiloToMega|mega|untilMega|megaToGiga|giga|gigaToTera|tera]
```

Avoid using `theme.breakpoints` directly, instead use the named media query helpers. The following media queries are available:

<MediaQueriesTable />

```ts
import { css } from '@emotion/react';

const styles = ({ theme }) => css`
  ${theme.mq.mega} {
    padding-top: ${theme.spacings.peta};
  }
`;
```
